<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Working with Sequenced Data Objects</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="sdo.sample.getset.html">Setting and Getting Property Values</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sdo.sample.reflection.html">Reflecting on Service Data Objects</a></div>
 <div class="up"><a href="sdo.examples.html">范例</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sdo.sample.sequence" class="section">
  <h2 class="title">Working with Sequenced Data Objects</h2>
  <p class="para">
   Sequenced data objects are SDOs which can track property
   ordering across the properties of a data object. They can also
   contain unstructured text elements (text element which do not
   belong to any of the SDO&#039;s properties).  Sequenced data objects are
   useful for working with XML documents which allow unstructured text (i.e.
   mixed=true) or if the elements can be interleaved (
   <div class="cdata"><pre>&lt;A/&gt;&lt;B/&gt;&lt;A/&gt;</pre></div>).  This can occur for example when
   the schema defines maxOccurs&gt;1 on a
   element which is a complexType with a choice order indicator.
  </p>
  <p class="para">
   The examples below assume an SDO created with the following schema
   and instance information, using the XML Data Access Service.
  </p>
  <p class="para">
   The schema below describes the format of a letter.  The letter can
   optionally contain three properties; date, firstName, and lastName.
   The schema states <strong class="command">mixed=&quot;true&quot;</strong> which means that
   unstructured text can be interspersed between the three properties.
  </p>
  <p class="para">
   <div class="example-contents">
<div class="xmlcode"><pre class="xmlcode">&lt;xsd:schema xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;
  xmlns:letter=&quot;http://letterSchema&quot;
  targetNamespace=&quot;http://letterSchema&quot;&gt;
  &lt;xsd:element name=&quot;letters&quot; type=&quot;letter:FormLetter&quot;/&gt;
  &lt;xsd:complexType name=&quot;FormLetter&quot; mixed=&quot;true&quot;&gt;
    &lt;xsd:sequence&gt;
      &lt;xsd:element name=&quot;date&quot; minOccurs=&quot;0&quot; type=&quot;xsd:string&quot;/&gt;
      &lt;xsd:element name=&quot;firstName&quot; minOccurs=&quot;0&quot; type=&quot;xsd:string&quot;/&gt;
      &lt;xsd:element name=&quot;lastName&quot; minOccurs=&quot;0&quot; type=&quot;xsd:string&quot;/&gt;
    &lt;/xsd:sequence&gt;
  &lt;/xsd:complexType&gt;
&lt;/xsd:schema&gt;</pre>
</div>
   </div>

  </p>

  <p class="para">
   The following is an instance letter document.  It contains the
   three letter properties; date, firstName and lastName, and has
   unstructured text elements for the address and letter body.
  </p>
  <p class="para">
   <div class="example-contents">
<div class="xmlcode"><pre class="xmlcode">&lt;letter:letters xmlns:letter=&quot;http://letterSchema&quot;&gt;
  &lt;date&gt;March 1, 2005&lt;/date&gt;
  Mutual of Omaha
  Wild Kingdom, USA
  Dear
  &lt;firstName&gt;Casy&lt;/firstName&gt;
  &lt;lastName&gt;Crocodile&lt;/lastName&gt;
  Please buy more shark repellent.
  Your premium is past due.
&lt;/letter:letters&gt;</pre>
</div>
   </div>

  </p>
  <p class="para">
   When loaded, the letter data object will have the sequence and
   property indices shown in the table below:
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>Sequence Index</th>
       <th>Property Index:Name</th>
       <th>Value</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>0</td>
       <td>0:date</td>
       <td>March 1, 2005</td>
      </tr>

      <tr>
       <td>1</td>
       <td>-</td>
       <td>Mutual of Omaha</td>
      </tr>

      <tr>
       <td>2</td>
       <td>-</td>
       <td>Wild Kingdom, USA</td>
      </tr>

      <tr>
       <td>3</td>
       <td>-</td>
       <td>Dear</td>
      </tr>

      <tr>
       <td>4</td>
       <td>1:firstName</td>
       <td>Casy</td>
      </tr>

      <tr>
       <td>5</td>
       <td>2:lastName</td>
       <td>Crocodile</td>
      </tr>

      <tr>
       <td>6</td>
       <td>-</td>
       <td>Please buy more shark repellent.</td>
      </tr>

      <tr>
       <td>7</td>
       <td>-</td>
       <td>Your premium is past due.</td>
      </tr>

     </tbody>
    
   </table>

  </p>

  <p class="para">
   To ensure sequence indices are maintained, sequenced data objects
   should be manipulated through the SDO_Sequence interface.  
   This allows the data object&#039;s instance data to be manipulated 
   in terms of the sequence index as opposed to the property index 
   (shown in the table above).  
   The following examples assume the letter instance has been 
   loaded into a data object referenced by the variable
   <strong class="command">$letter</strong>.
   <div class="example" id="example-5338">
    <p><strong>Example #1 Getting the SDO_Sequence interface</strong></p>
    <div class="example-contents"><p>
     We obtain a data object&#039;s sequence using the
     <span class="function"><strong>getSequence()</strong></span>
     method. The follow gets the
     sequence for the letter data object.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />&nbsp;&nbsp;$letter_seq&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$letter</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getSequence</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>
  <p class="para">
   All subsequent examples assume that the
   <strong class="command">$letter_seq</strong>
   variable has been assigned the sequence for the letter data object.
  </p>

  <p class="para">
   <div class="example" id="example-5339">
    <p><strong>Example #2 Get/set sequence values</strong></p>
    <div class="example-contents"><p>
     We can get and set individual values (including unstructured text)
     using the sequence index.  
     The following sets the firstName to &#039;Snappy&#039; and gets the last 
     sequence values (the unstructured text, &#039;Your premium is past due.&#039;).
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />&nbsp;&nbsp;$letter_seq</span><span style="color: #007700">[</span><span style="color: #0000BB">4</span><span style="color: #007700">]&nbsp;=&nbsp;</span><span style="color: #DD0000">'Snappy'</span><span style="color: #007700">;<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$text&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">[</span><span style="color: #0000BB">count</span><span style="color: #007700">(</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">)&nbsp;-&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">];<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>

  <p class="para">
   <div class="example" id="example-5340">
    <p><strong>Example #3 Sequence iteration</strong></p>
    <div class="example-contents"><p>
     We can iterate through the individual sequence values using <a href="control-structures.foreach.html" class="link">foreach</a>.
     The following runs through the individual values in sequence order.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">foreach&nbsp;(</span><span style="color: #0000BB">$letter</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getSequence</span><span style="color: #007700">()&nbsp;as&nbsp;</span><span style="color: #0000BB">$value</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;...<br /></span><span style="color: #007700">}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>

  <p class="para">
   <div class="example" id="example-5341">
    <p><strong>Example #4 Sequence versus Data Object</strong></p>
    <div class="example-contents"><p>
     Setting values through the data object interface may result in the
     value not being part of the sequence.  A value set through the data
     object will only be accessible through the sequence if the property was
     already part of the sequence. The following example sets the
     lastName through the data object and gets it through the sequence.
     This is fine because lastName already exists in the sequence.  If
     it had not previously been set, then lastName would be set to
     &#039;Smith&#039;, but would not be part of the sequence.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />&nbsp;&nbsp;$letter</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">]&nbsp;=&nbsp;</span><span style="color: #DD0000">'Smith'</span><span style="color: #007700">;<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$last_name&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">[</span><span style="color: #0000BB">5</span><span style="color: #007700">];<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>

  <p class="para">
   <div class="example" id="example-5342">
    <p><strong>Example #5 Adding to a sequence</strong></p>
    <div class="example-contents"><p>
     We can add new values to a sequence using the
     <span class="function"><a href="sdo-sequence.insert.html" class="function">SDO_Sequence::insert()</a></span>
     method.  The following examples assume that the &#039;firstName&#039; and 
     &#039;lastName&#039; properties are initially unset.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;Append&nbsp;a&nbsp;firstName&nbsp;value&nbsp;to&nbsp;the&nbsp;sequence<br />&nbsp;&nbsp;//&nbsp;value:&nbsp;'Smith'<br />&nbsp;&nbsp;//&nbsp;sequence&nbsp;index:&nbsp;NULL&nbsp;(append)<br />&nbsp;&nbsp;//&nbsp;propertyIdentifier:&nbsp;1&nbsp;(firtName&nbsp;property&nbsp;index)<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #DD0000">'Smith'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">NULL</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;Append&nbsp;a&nbsp;lastName&nbsp;value&nbsp;to&nbsp;the&nbsp;sequence<br />&nbsp;&nbsp;//&nbsp;value:&nbsp;'Jones'<br />&nbsp;&nbsp;//&nbsp;sequence&nbsp;index:&nbsp;NULL&nbsp;(append)<br />&nbsp;&nbsp;//&nbsp;propertyIdentifier:&nbsp;'lastName'&nbsp;(lastName&nbsp;property&nbsp;name)<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #DD0000">'Jones'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">NULL</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'lastName'</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;Append&nbsp;unstructured&nbsp;text<br />&nbsp;&nbsp;//&nbsp;value:&nbsp;'Cancel&nbsp;Subscription.'<br />&nbsp;&nbsp;//&nbsp;sequence&nbsp;index:&nbsp;absent&nbsp;(append)<br />&nbsp;&nbsp;//&nbsp;propertyIdentifier:&nbsp;absent&nbsp;(unstructured&nbsp;text)<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #DD0000">'Cancel&nbsp;Subscription.'</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;</span><span style="color: #FF8000">//&nbsp;Insert&nbsp;new&nbsp;unstructured&nbsp;text.&nbsp;&nbsp;Subsequent&nbsp;sequence&nbsp;values<br />&nbsp;&nbsp;//&nbsp;are&nbsp;shifted&nbsp;up.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />&nbsp;&nbsp;//&nbsp;value:&nbsp;'Care&nbsp;of:'<br />&nbsp;&nbsp;//&nbsp;sequence&nbsp;index:&nbsp;1&nbsp;(insert&nbsp;as&nbsp;second&nbsp;element)<br />&nbsp;&nbsp;//&nbsp;propertyIdentifier:&nbsp;absent&nbsp;(unstructured&nbsp;text)<br />&nbsp;&nbsp;</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #DD0000">'Care&nbsp;of:'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>

  <p class="para">
   <div class="example" id="example-5343">
    <p><strong>Example #6 Removing from a sequence</strong></p>
    <div class="example-contents"><p>
     We can use the <span class="function"><a href="function.isset.html" class="function">isset()</a></span>  and
     <span class="function"><a href="function.unset.html" class="function">unset()</a></span> functions to test and remove items
     from the sequence (Note: <span class="function"><a href="function.unset.html" class="function">unset()</a></span> currently
     leaves the values in the data object, but this behaviour is
     likely to change to also remove the data from the data object).
     A sequence behaves like a contiguous list; therefore, removing
     items from the middle will shift entries at higher indices
     down. The following example tests to see if the first sequence
     element is set and unsets it if is.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />&nbsp;&nbsp;</span><span style="color: #007700">if&nbsp;(isset(</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]))&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;unset(</span><span style="color: #0000BB">$letter_seq</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]);<br />&nbsp;&nbsp;}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>

 </div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="sdo.sample.getset.html">Setting and Getting Property Values</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sdo.sample.reflection.html">Reflecting on Service Data Objects</a></div>
 <div class="up"><a href="sdo.examples.html">范例</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
